Discontinuity set object methods

Discontinuity set objects are a Lua wrapper over a GeMA discontinuity set providing a rich set of methods for querying and updating its properties and storing a set of discontinuity objects. Discontinuity set objects can be obtained in the orchestration by calling the modelData:discontinuitySet() method.

Example:

local ds = modelData:discontinuitySet('dsName')

Index:

• Metadata methods
  • ds:id()
  • ds:description()
  • ds:type()
  • ds:mesh()
  • ds:spatialIndex()
  • ds:autoAddElements()
  • ds:extraDofsInAddedElements()
  • ds:snapTolerance()
  • ds:repelTolerance()
  • ds:repelDistance()
• Setup data methods
  • ds:setDiscontinuityData()
• Discontinuity methods
  • ds:numDiscontinuities()
  • ds:discontinuityIndex()
  • ds:discontinuity()
• Attribute methods
  • ds:attributeIds()
  • ds:attributeInfo()
  • ds:attributeAccessor()
  • ds:numAttributeStates()
• Property methods
  • ds:numPropertySets()
  • ds:propertySets()
  • ds:propertySetIndex()
  • ds:propertyInfo()
  • ds:propertyAccessor()
• Intersection methods
  • ds:cellIntersections()
• Other methods
  • ds:print()
  • ds:visibility()

Metadata methods

ds:id()
Description:	Returns the discontinuity set name.
Parameters:	None.
Returns:	Returns a string with the discontinuity set name (the id attribute given during its model definition).

Example:

-- Print the discontinuity set name
print(ds:id())

ds:description()
Description:	Returns the discontinuity set description.
Parameters:	None.
Returns:	Returns a string with the discontinuity set description

Example:

-- Print the discontinuity set description
print(ds:description())

ds:type()
Description:	Returns the discontinuity set geometry type as a string. Available types are "polyline", "tri. surface", "edge list" and "face list".
Parameters:	None.
Returns:	Returns a string with the discontinuity set geometry type.

Example:

-- Print the discontinuity set geometry type
print(ds:type())

ds:mesh()
Description:	Returns the cell mesh object owning the cells that are "cut" by the given discontinuities.
Parameters:	None.
Returns:	Returns the associated cell mesh object.

Example:

local mesh = ds:mesh()

ds:spatialIndex()
Description:	Returns the optional spatial index object used by the discontinuity set object to accelerate intersection operations.
Parameters:	None.
Returns:	Returns the associated spatial index object or nil if there is none.

Example:

local si = ds:spatialIndex()

ds:autoAddElements()
Description:	Returns true if the intersection between the discontinuity set discontinuities and the support mesh should be added to the mesh as new elements. The added elements type depend on the discontinuity geometric type. Polyline geometries are added as bars, edge lists are added as interface elments, triangle surfaces are added either as 3d triangles or quads and face lists are added as 3d interface elements.
Parameters:	None.
Returns:	Returns a boolean defining if the discontinuity is automatically added to the mesh as new elements.

Example:

local autoAdd = ds:autoAddElements()

ds:extraDofsInAddedElements()
Description:	Returns true if added interface elements should have extra dof nodes in its middle plane. This option only has effect if elements are added automatically to the mesh and the geometric discontinuity type is either edge list or face list.
Parameters:	None.
Returns:	Returns a boolean defining if added interface elemenst should have extra dof nodes or not.

Example:

local extraDofs = ds:extraDofsInAddedElements()

ds:snapTolerance()
Description:	Returns the percentual tolerance used to snap discontinuity-cell intersection points to cell nodes, edges or faces. See comments on the snapTol option field at the discontinuity set object documentation for an in-depth explanation of the tolerance role.
Parameters:	None.
Returns:	Returns the defined tolerance.

Example:

local tol = ds:snapTolerance()

ds:repelTolerance()
Description:	Returns the percentual tolerance used to detect discontinuity-cell intersection points which should be repelled from cell nodes. See comments on the repelTol option field at the discontinuity set object documentation for an in-depth explanation of the tolerance role.
Parameters:	None.
Returns:	Returns the defined tolerance.

Example:

local tol = ds:repelTolerance()

ds:repelDistance()
Description:	Returns the percentual distance used to repel discontinuity-cell intersection points from cell nodes. See comments on the repelDistance option field at the discontinuity set object documentation for an in-depth explanation of the distance role.
Parameters:	None.
Returns:	Returns the defined distance.

Example:

local dist = ds:repelDistance()

Setup Data method

ds:setDiscontinuityData(data, attributes, properties)
Description:	Given an empty discontinuitySet created with modelData: addNewEmptyDiscSet() setup its attributes, properties and geometries. All parameters follows the same format as the model reference discontinuitySet
Parameters:	data	The geometry data for the discontinuity Set.
	attributes	A table of attributes for the discontinuity Set.
	properties	A table of strings naming properties.
Returns:	None.

Example:

local attributes = {
    {id = 'a1', description = 'A discontinuity attribute',               unit = 'm'},
    {id = 'a2', description = 'Another discontinuity attribute',         dim = 2},
    {id = 'a3', description = 'An attribute incompatible with the mesh'},
    {id = 'a4', description = 'An attribute that does not exist in the mesh'},
    {id = 'a5', description = 'An attribute with incompatible unit',     unit = 's'},
    {id = 'a6', description = 'An attribute with unit conversion',       unit = 'cm'},
  }
  
  local properties = {'PSet2', 'PSet1'}
  
  local data = {
    {id = 'P1', polyline = ds1Polyline1, attributeValues = {1, {10, 100}, 3.1, 4.1, 5.1, 1001}, PSet1 = 2,    PSet2 = 1, cellGroup = 'P1'},
    {id = 'P2', polyline = ds1Polyline2, attributeValues = {2, {20, 200}, 3.2, 4.2, 5.2, 1002}, PSet1 = 3,    PSet2 = 1, cellGroup = 'P2'},
    {id = 'P3', polyline = ds1Polyline3, attributeValues = {3, {30, 300}, 3.4, 4.3, 5.3, 1003}, PSet1 = 'M2', PSet2 = 1},
    {id = 'P4', polyline = ds1Polyline4, attributeValues = {4, {40, 400}, 3.5, 4.4, 5.4, 1004}, PSet1 = 'M3', PSet2 = 'M1'},
  }
 
  ds:setDiscontinuityData(data, attributes, properties)

Discontinuity methods

ds:numDiscontinuities()
Description:	Returns the number of discontinuities in this discontinuity set.
Parameters:	None.
Returns:	Returns the number of discontinuities.

Example:

local ndisc = ds:numDiscontinuities()

ds:discontinuityIndex(name)
Description:	Returns the index in the discontinuity set of the named discontinuity or nil if not found.
Parameters:	name - The discontinuity name (id).
Returns:	Returns the index of the given discontinuity in the set or nil if not found.

Example:

local index = ds:discontinuityIndex('discName') -- Returns the index in ds of the discontinuity named 'discName'

ds:discontinuity(index)
Description:	Returns the discontinuity object stored at the given index.
Parameters:	index - The discontinuity index, a value between 1 and ds:numDiscontinuities().
Returns:	Returns the discontinuity object.

Example:

local d = ds:discontinuity(1) -- Returns the first discontinuity object in the set

Attribute methods

ds:attributeIds()
Description:	Returns a list with the name (id) of every attribute associated with the discontinuity set.
Parameters:	None.
Returns:	Returns a table with attribute ids (strings).

Example:

local attrIds = ds:attributeIds() 

ds:attributeInfo(name)
Description:	Returns an object with metadata information about the named discontinuity set attribute.
Parameters:	name - The attribute name (id).
Returns:	Returns a value info object or nil if the requested name was not found in the discontinuity set.

Example:

local rhoInfo = ds:attributeInfo('rho') 

ds:attributeAccessor(name, unit) ds:attributeAccessor(name, state, locked, unit)
Description:	Returns a Discontinuity accessor object that can be used to retrieve and update data for discontinuity attributes. Can be called with two different signatures. The first, receiving only the attribute name and an optional unit, always retrieves data from the current state and is the most used. The second, allows for defining the desired state from which data will be recovered / written. As a matter of fact, the first format is equivalent to calling the second one as ds:attributeAccessor(name, 0, true, unit).
Parameters:	name	The name (id) of the discontinuity set attribute.
	state	An optional state number referencing the history state that the accessor will operate on. A value of zero means the most recent state, 1 the previous one, 2 the one before that and so on. Valid values range from zero to the oldest state for the requested variable, which can be queried with a call to ds:numAttributeStates(). Remember that for a discontinuity accessor to support states, the history parameter must be set on its value info object.
	locked	The locked parameter controls the behaviour of the accessor once a new state is created for the value. The 'lock' refers to the state number, so if locked is false and a new state is created, the accessor doesn't change and continues to point to the same data. If locked is true, the accessor will be locked to that state number, so when a new state is created, the accessor changes the data its looking upon to reflect the new state. For example, an accessor locked on state 0 will always point to the current state, and one locked to state 1 will always point to the previous saved value.
	unit	An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns:	A Discontinuity accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local rhoAc  = ds:attributeAccessor('rho')          -- Get an accessor to the 'rho' discontinuity set attribute
local rhoAc2 = ds:attributeAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' discontinuity set attribute with values converted to g/cm3
local rhoAc3 = ds:attributeAccessor('rho', 1, true) -- Get an accessor locked on the previous saved value of attribute 'rho'

ds:numAttributeStates(name)
Description:	Returns the number of existing history states for the given discontinuity attribute.
Parameters:	name - The name (id) of the discontinuity attribute.
Returns:	Returns the number of existing states or -1 for unknown names.

Example:

local nstates = ds:numAttributeStates('rho')

Property methods

ds:numPropertySets()
Description:	Returns the number of property sets attached to this discontinuity set.
Parameters:	None.
Returns:	Returns the number of property sets.

Example:

local npsets = ds:numPropertySets()

ds:propertySets()
Description:	Returns a list with the property set objects attached to this discontinuity set.
Parameters:	None.
Returns:	Returns a list of property set objects.

Example:

-- Prints the name of the property sets attached to this discontinuity set
local psets = ds:propertySets()
 
for i = 1, #psets do
  print(psets[i]:id())
end

ds:propertySetIndex(name)
Description:	Returns the index of the associated property set that includes the given property name.
Parameters:	name - The property name.
Returns:	Returns the index inside the list returned by ds:propertySets() of the property set object that contains 'name' among its properties. Returns nil for unknown names.

Example:

local psetIndex = ds:propertySetIndex('rho')

ds:propertyInfo(name)
Description:	Returns an object with metadata information about the named discontinuity property.
Parameters:	name - The property name (id).
Returns:	Returns a value info object or nil if the requested name was not found in the discontinuity set.

Example:

local rhoInfo = ds:propertyInfo('rho') 

ds:propertyAccessor(name, unit)
Description:	Returns a Discontinuity accessor object that can be used to retrieve data for discontinuity properties. Unlike other accessor types, a property accessor always retrieves data from the current state.
Parameters:	name	The name (id) of the discontinuity property.
	unit	An optional string with the desired unit for returned values. If different from the data unit, the accessor will automatically convert values.
Returns:	A Discontinuity accessor object or nil on errors (the requested name is unknown, or the requested unit is incompatible with the data unit, for example).

Example:

local rhoAc  = ds:propertyAccessor('rho')          -- Get an accessor to the 'rho' property
local rhoAc2 = ds:propertyAccessor('rho', 'g/cm3') -- Get an accessor to the 'rho' property with values converted to g/cm3

Intersection methods

ds:cellIntersections(cellId)
Description:	Returns intersection data for the intersections that where found between the given cell and the discontinuies from this set. Returns nil if there are none. The returned data varies according to the discontinuity set type. For 2D polyline it is a table with one sub-table for each cell-discontinuity intersection. For 3D triangle surface it is a single table.
Parameters:	cellId - The cell id number (an index between 1 and mesh:numCells()) for the queried cell.
Returns:	Returns the discontinuity-cell intersection data or nil if there is none. For polyline-cell intersections, the following fields are present in each data sub-table: - cellId; - discontinuityIndex: The index of the discontinuity in the discontinuity set; - segmentIndex: The polyline segment index inside the discontiinuity; - edge: Set to the cell edge index if the intersection lies over an edge. Not present if the intersection just crosses an edge or a node. See the Element types page for the edge organization for each cell type; - intersectionElement: The id for the added intersection element when autoAddElements is enabled for this discontinuity set. Not presente otherwise; - in: A table storing coordinates and metadata for the first, or incoming, intersection between the segment and the cell. Its fields are: kind, a string specifying if the intersection was on an edge, a node or internal to the cell, border, an integer filled with the edge or node index for those kinds of intersection and absent for internal ones, cartCoord, a vector object filled with cartesian coordinates for the intersection and natCoord, a vector object filled with the intersection natural coordinates; - out: Similar to in but storing the data for the second, or outgoing, intersection between the segment and the cell. For 3d surface-cell intersections,let N be the number of points and M the number of triangles, the following fields are present: - cellId; - cartCoord: Matrix 3xN of intersection points in cartesial coordinates. - natCoord: Matrix KxN of intersection points in natural coordinates (K is the dimension of the natural coordinates, which may vary with element type). - discNormal: Matrix 3x(number of discontinuities in the cell) averaged normals from original triangle intersections (it may differ from the normal computed from the actual intersection triangulation). - triIndex: Matrix 3xM with indexes of points for each of the M triangles. - triDiscontinuityId: Table with indexes 1..M where each value is the discontinuity associated with the triangle j \in 1 to M (column of triIndex). - pointType Table with indexes 1..N where each value is a pair (discIndex, intersecType) associated with point i \in 1 to N (column of cartCoord/natCoord). Points shared between discontinuities will have discIndex equal to 0 and intersecType is a string (None, Node, Edge, Face, Internal). - triElementId: A table containing the mesh element associated with each triangle. This table is only set when the option autoAddElements is true.

Example 2D:

-- Get intersection for the third cell
local d = ds:cellIntersections(3) 
 
if not d then
  print('No intersections')
else
  -- Print the index of the bar element that represents each intersection
  -- and also the cartesian coordinates of each intersection endpoint
  if ds:type() == 'polyline' then
    for i, v in ipairs(d) do
      print(v.intersectionElement)
      v.in.cartCoord:t():print()  -- Vector is transposed before printing for a better layout
      v.out.cartCoord:t():print() 
    end
  end
end

Example 3D:

-- Get intersection for the third cell
local d = ds:cellIntersections(3) 
 
if not d then
  print('No intersections')
else
  -- Print all triangles and properties for the cell intersection
  if ds:type() == 'tri. surface' then
      print('cell Id', d['cellId'])
          
          print('Cartesian Coordinates:')
          d['cartCoord']:t():print()
          
          print('Natural Coordinates:')
          d['natCoord']:t():print()
          
          print('Discontinuity Normals:')
          int3d['discNormal']:t():print()
          
          print('Triangle Index:')
          d['triIndex']:t():print()
          
          print('Triangle Discontinuity Id:')
          for i, v in ipairs(d['triDiscontinuityId']) do
                print('TriangleId', i, 'DiscontinuityId', v)
          end
          
          print('Point Type:')
          for i, v in ipairs(d['pointType']) do
                print('PointId', i, 'DiscontinuityId', v['discIndex'], 'IntersectionType', v['IntersecType'])
          end
          
    end
  end
end

Other methods

ds:print()
Description:	Print discontinuity set parameters together with attribute values and geometry definition for each discontinuity in the set.
Parameters:	None.
Returns:	Nothing.

Example:

ds:print()

ds:visibility(pointA, pointB), ds:visibility(pointA, pointB, eps)
Description:	Checks if are directly visible from one to another without a discontinuity blocking.
Parameters:	pointA, pointB:	a pair of points coordinates to check the visibility. Can be either a table or a vector object and shoud have the same dimension as the mesh the discontinuity lies on.
	eps:	(Optional)Points with distance less than |eps| are considered to lie on the discontinuity, hence their visibility is true always. (Default = 0.0)
Returns:	True if pointA is visible from pointB (there is a straight line connecting then) or False otherwise.

Example:

ds:visibility({0,0,0}, {5,5,5})
ds:visibility({0,0,0}, {5,5,5}, 1e-8)